XMLFacade Plugin Howto

It's extremely easy to write your own plugin if you have a DTD or an XSD for the XML you want your plugin to generate. XDoclet's built-in xmlfacade plugin will build all the scaffolding code for you, so the only thing you have to concentrate about is to pull data from the sources and stuff them into the XML.

We'll see shortly how you can use various APIs to do this.

Building the scaffold logic.

The first you'll have to do is to set up a little project space for your plugin code.

maven.xml project.xml project.properties src/ +--dtd/ | +--hello-1.0.dtd | +--hello-1.1.dtd | +--java/ +--dummy.txt

That's all you need to get started. No java code at all! Just some configuration files.

run maven

This will generate the API you need to generate the XML.

Building the stuffing logic.

What you just generated is an API that can produce XML. Now you must write some ocde that uses this API and "stuffs" in data from your @tags.

sources + tags -> your code -> xml generator API.

Think about your code as something that sits in the middle of two APIs. It uses the left API to get the data and the right API to generate XML.

The left API is the xjavadoc API. This is an API that is similar to Sun's javadoc API, and it lets you access all the information you need from the @tagged sources.

The right API is the API that was generated for the DTDs and XSDs you provided.

An XML document is actually a tree. A tree has a root node, and several child nodes. Child nodes can be leaves or they can in turn have more child nodes.

Your job is to build the tree that corresponds to the XML you want to generate. We recommend that you write one fill() method for each element type.

Take a look at the hibernate plugin. Note that you don't have to check for nullity. The facade will silently ignore (it won't pass along) if you pass a null value.

This "silence" behaviour could also be used if an unsupported method is called.

If you're using a good IDE, you'll be helped by code completion. You want to look for setXXX and createXXX methods. It's also a good idea to try to keep the same order in the code as in the DTD or XML Schena. That makes it easier to discover if you have forgotten an element or an attribute.

Conclusion

You might be a little overwhelmed by the size of the plugin and the number of classes. This size is the price to pay for an XDoclet that's easy to extend and generates a lot of the logic for you. So at the cost of size you get reduced development time of plugins, less bugs and hopefully a very fast plugin.

Further, you don't have to maintain several versions of the same plugin just because there are several versions of a DTD or XSD or even both. XDoclet will always generate one "facade" API that you can use.